Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add skeleton for constructor manager documentation #113

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

goanpeca
Copy link

@goanpeca goanpeca commented Feb 22, 2023

Description

Type of change

  • Fixes or improves existing content
  • Adds new content page(s)
  • Fixes or improves workflow, documentation build or deployment

References

Final checklist:

  • My PR is the minimum possible work for the desired functionality
  • I have commented my code, particularly in hard-to-understand areas
  • I have added alt text to new images included in this PR

@github-actions github-actions bot added the documentation Improvements or additions to documentation label Feb 22, 2023
Copy link
Contributor

@aganders3 aganders3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great improvements - thanks for working on this!

Constructor installers come with a `constructor-manager` stack that allows users to perform
"updates in place", recover from a broken installation, rollback to a previous version or restore
point and finally uninstall the entire application. The constructor manager stack is application
agnostic in that it can be used for any othe application using the updated constructor stack
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
agnostic in that it can be used for any othe application using the updated constructor stack
agnostic in that it can be used for any other application using the updated constructor stack

Comment on lines +324 to +328
* `constructor-manager-backend`: Provides a simplified command line interface on top of
`conda`, `mamba` and `conda-lock` to query for updates and perform the actual installation,
reset or uninstallation of the application.
* `constructor-manager-client`: Provides a Python API to interact with the backend and
perform the same operations as the CLI.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a little confusing to me. I guess I would consider the Python API the backend and the CLI to be the client? You know more about the implementation though so I defer to you on naming.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @aganders3 yes indeed this might be confusing. Let me explain and from there we can make adjustments

The backend right now is only a CLI, that under the hood calls mamba, conda, conda-lock, and does a bunch of admin work for us (update in place, restore points etc). This could be updated eventually to become something more of a cli, for example an actual server doing things. So in this case instead of pinging a local server, we ping an actual program CLI.

The client is what we use to communicate with this backend (currently a cli but maybe a server in the future). So that is why I went with that naming scheme. The client could be renamed API. I called it like that in the past actually. But in this case is one thing we use to communicate and do thins with the "server" (like a frontend backend thing).

But I am open to suggestions, not super important but I would like to get the naming "right" before publishing packages

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used to have the names

constructor-manager-cli and constructor-manager-api which were pretty accurate in what they are now, the new ones are more generic, maybe I should stick to those old names @aganders3 ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks - this makes sense.

I agree the names are not super important because the descriptions make things clear. I think I do prefer constructor-manager-cli and constructor-manager-api but not by a wide margin, and the new names leave things more open to changes down the line. Maybe split the difference and keep constructor-manager-backend and constructor-manager-api?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will go with constructor-manager and constructor-manager-api, that way we leave the cli to be more open and add a specific entrypoint in there constructor-manager-cli and leave the api one as the api that it is :)

Thanks for the feedback

Comment on lines +390 to +408
* `check_updates`: Query for new updates available for the managed application by providing one
or more anaconda.org channels. By default we query the `conda-forge` channel located at [anaconda.org](https://anaconda.org/conda-forge/).
* `update`: update a current application to a new version of it. This process will create a new
conda environment following the convention `<package-name>-<new-version>`, create new menu
shortcuts [20], create a new restore point (using conda-lock), remove the old environment and
the corresponding shortcuts for the old versions of the managed application.
* `revert`: this will revert the current application to the previously installed version on the
computer if a restore point is found. This will follow a similar process of creating a new conda
environment with the convention `<package-name>-<old-version>`.
* `restore`: similar to revert but restore to a previously found state of the current version.
This command could become a single one by providing the specific restore file (which is created
by conda lock).
* `lock_environment`: create a lock file of the current state of the application environment.
This can be called by the client applications (using constructor-manager-client) to check
for changes in the environment. If no changes are detected, no lock is created.
* `uninstall`: to be implemented
* `get_status`: get information on a currently running update/restore/revert in progress.
* `open_application`: open a give application created with `conda` and `menuinst` un a cross
platform way
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think you need to repeat all this here. Maybe just list any limitations of this API vs. the backend/CLI.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed, this was a lot of repetition, will update!

@@ -332,4 +448,6 @@ a high-level list of the main changes introduced in the stack.
[16]: https://github.com/conda-forge/napari-feedstock/pulls?q=is%3Apr+sort%3Aupdated-desc+is%3Aclosed
[17]: https://anaconda.org/napari
[18]: https://github.com/napari/packaging/issues/15
[19]: https://github.com/napari/packaging
[20]: https://github.com/conda/menuinst/tree/cep-devel/menuinst
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be a typo but I'd just link to the root of the tree where the README is.

Suggested change
[20]: https://github.com/conda/menuinst/tree/cep-devel/menuinst
[20]: https://github.com/conda/menuinst/tree/cep-devel

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. Yes, I think I copied the wrong link whoops!


##### `constructor-manager-ui`

which in its present form is a pyqt/pyside based application. It provides a graphical interface
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
which in its present form is a pyqt/pyside based application. It provides a graphical interface
In its present form this is a pyqt/pyside based application. It provides a graphical interface

@melissawm
Copy link
Member

Hi all! Is this something we are still planning to do? If so, can I help push it forward? Thanks!

@melissawm
Copy link
Member

Gentle re-ping just to get a status on this 😄

@aganders3
Copy link
Contributor

From my perspective I think this is back-burner for the time being. I think more effort is being put into the plugin manager compared to the constructor manager (this project) for the time being. @goanpeca probably has a better idea at this point, though!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
Development

Successfully merging this pull request may close these issues.

3 participants